Whiteline: delta/whiteline CD Series - delta.iso/tools/falc_uti/falcextn/falcextn.txt

Text File | 1995-11-25 | 40KB | 1,126 lines

Instructions for the Falcon Extension (v1.1a)

Contents

   * Introduction.
        o Introduction.
        o Getting STOS to run on the Falcon.
        o Registering this software.
   *  Command descriptions :-
        o General
             + cache
             + cookie
             + falc help
             + jagpad
             + lfalc help
             + monitor
             + os version
             + set cache
        o Graphics
             + cycle
             + df video
             + falc bar
             + falc box
             + falc cls
             + falc colour
             + falc draw
             + falc ink
             + falc mkey
             + falc mouse off
             + falc mouse on
             + falc plot
             + falc set mouse
             + falc set zone
             + falc x mouse
             + falc y mouse
             + falc zone
             + fpal
             + gdos font
             + goraud
             + init goraud
             + init virtual
             + planes
             + quick fade
             + scrsize
             + set fpal
             + set fv
             + set video
             + st compat
             + tc collide
             + tc copy
             + tc fade
             + tc point
             + tc scrn fade
             + tc sprite
             + tc text
             + tga decode
             + tga height
             + tga width
             + virtual
             + xres
             + yres
        o Sound
             + dsp clear
             + dsp play
             + dsp process
             + dsp stop
             + dtm inst
             + dtm name
             + dtm play
             + dtm stop
             + dtm voices
             + falc freq
             + falc mic thru
             + falc sammde
             + falc sam play
             + falc sample
             + falc sampos
             + falc samstop
             + set gain / lgain / rgain
             + set volume / lvolume / rvolume
             + speaker on/off
             + tracker inst
             + tracker name
   * Commands in progress.
   * Version history.
   * Credits.

Introduction

This extension has been written to allow STOS to take advantage of the new
facilities provided by the Atari Falcon. The current version only touches on
some areas of the Falcons abilities very lightly. Future versions will
hopefully go further, making programming the Falcon easier, without the need to
resort to coding in assembler, or C.

To install the extension, simply copy the files FGRAPHIC.EXX and FAUDIO.EXY
into the STOS folder, and FGRAPHIC.ECX, FAUDIO.EXY into the compiler directory.

When STOS initializes the graphics extension, it will select the correct Falcon
resolution, so that STOS goes to a ST compatible screen rez, whatever you were
in before running STOS. The initial resolution is not restored upon exit. In a
screen mode where the vertical resolution is >=400 ST High will be chosen.
Otherwise, ST Medium will be set. This will only be done on TOS 4 and above (-
should TOS 5 every be released...).

This extension is SHAREWARE, so if you like it (or use it!!) then you should
send me some money... See below for details.


Getting STOS to run on the Falcon.

Due to the way that STOS was originally written, STOS does not work correctly
on the Falcon without patching. Even with patching, not all of the bugs can be
removed. Some of the problems encountered are listed below, along with a
sollution.

   * Problem: The mouse does not respond.
     Solution: Use STOS Fix 3.0 or above to patch basic206.prg
   * Problem: The joysticks do not work.
     Solution: Use STOS Fix 3.
   * Problem: The keyclick goes wild.
     Solution: Use STOS Fix 3 (not BASICMJH.PRG)
   * Problem: Graphics functions dont work.
     Solution: Un-patched. Use graphics functions from an extension. (This
     one?)
   * Problem: Computer crashes apon quiting.
     Solution: Use STOS Fix 3.
   * Problem: Change mouse to user defined doesn't work.
     Solution: Un-patched. Use sprite x mouse,y mouse.
   * Problem: Palettes are not correctly set.
     Solution: try SET FPAL in this extension.....
   * Problem: Running STOS from >= 400 vertical resolution mode does not work.
     Solution: Install this extension! This will set it to ST High mode if this
     is the starting resolution.

As you can see, STOS Fix is essential to use STOS on a Falcon. Remember that
your compiled programs will suffer from the above problems unless they are also
patched with STOS fix. I have found that if patched on TOS 4.04 they also work
under TOS 4.01 and TOS 4.92a (hmmmm...). However, this should not be relied
apon without further testing, and so, a note to this effect should be placed in
the documentation of any released software.

STOS, will run under MultiTOS, so do not try.... I have found, however, that
compiled versions sometimes work... give 'em a go!


Registering.

This extension is shareware, and so, if you like it/use it, you owe me some
money! As we all know, students are not the richest of people, so I can assure
you that I could certainly use some cash...

I am only asking for 5 pounds (sterling), so it's not much....

If you register, you get a the latest version, along with a compiler that does
not display the fact that you have not registered before running you program. I
will also send you some example source code showing how to use some of the
commands.

Registered users may write to me, with questions/requests and I will do my best
to answer them. If you have internet access, I can send you all of the above
via email (during the academic year), along with regular updates, if you want
them...

If you dont feel that this extension is worth 5 pounds, write to me, telling me
what is wrong with it (eg. commands/bugs etc), and I will try to fix it...

To register, simply send me 5 UK pounds (cheques payable to Anthony Jacques)
at:

STOS Falcon Extension registrations,
70 West Avenue,
Oldfield Park,
Bath,
Avon.
BA2 3QD
ENGLAND

or, during the 95/96 academic year,

STOS Falcon Extension registrations,
Anthony Jacques
25 Balleratt Street
Levensulme
Manchester
England


Command descriptions.

Following is a list of the instructions/functions, and what they do.

Some of these instructions assume a Falcon. If a falcon specific instruction is
called on an ST, I do not know what will happen. (I would guess a bus error or
illegal instruction). The user should test what machine the program is running
on first (either using os version, or cookie).


General

x=cache

This function returns the current state of the '030 instruction and data
caches. The result is represented by a sequence of bits. They are encoded in in
the same way as in SET CACHE.

x=cookie(cook)

This function returns the value of the given cookie. If there is no cookie jar,
or the cookie is not found, it returns a "Not Found" error.

eg.
10 print cookie("_MCH")

will print the value of the _MCH (machine) cookie. On a TOS 1.0 FM this will
give the error message "Not Found in line 10."

A list of cookie ID's and the ascoiated meanings can be found on the WWW (email
me for an address). The Atari cookies are also listed in Hisofts Modern Atari
System Software - Appendix C.

falc help

This instruction displays on screen the syntax of each command available in
this extension. This is designed to make it easier to use the commands.

As this is intended for editor use, this instruction cannot be compiled.

x=jagpad(port)

This function returns a binary value giving the state of each of the 21 keys on
a Jaguar controller connected the the extended controller port PORT (0-1) The
value returned allows the programmer to detect any combination of keys.

The bitwise representation of this value is :-

1 4 7 * 3 6 9 # 2 5 8 0 o p c b a r l d u

Where o = option, p = pause, a/b/c = fire buttons r/l/d/u=directions, and the
others are keys on the "phone pad".

Each bit can be tested by anding with the bitwise value
ie
10 x=jagpad(0) : if (x and %10) then down
20 if (x and %1) then up

lfalc help

This instruction sends the help screen that is displayed by FALC HELP to the
printer. This should be used if you do not intend to print out this manual.

As this is intended for editor use, this instruction cannot be compiled.

x=monitor

This returns the monitor type that is currently connected.

The form of x is :-
0 = ST mono monitor
1 = ST colour monitor
2 = (S)VGA monitor
3 = Television.

There is no method of distinguishing VGA and SVGA monitors. SVGA are capable of
a wider range of frequencies and resolutions, but you will have to take the
word of the user that their monitor can cope.

x=os version

This function returns the OS version. The radix point is not inserted, but is
always two digits from the right. (eg. $404 = $4.04)

eg. 10 print hex$(os version)

set cache VALUE

This instruction sets the current state of the cache. VALUE is encoded in the
following way:

x x x x x x x x x x x
| | | | | | | | | | |__ Enable Intruction cache.
| | | | | | | | | ----- Freeze instruction cache.
| | | | | | | | ------- Clear instruction entry.
| | | | | | | --------- Clear instruction cache.
| | | | | | ----------- Instruction burst enable.
| | | | | --- Enable data cache.
| | | | ----- Freeze data cache.
| | | ------- Clear data entry.
| | --------- Clear data cache.
| ----------- Data burst enable.
------ Write allocate

As you can see, it is quite complex. However, for optimum speed, a value of
12561 should be passed.

NOTE: Encoding technique is likely to change (to simply on/off).

Graphics

cycle index,count

This instruction cycles COUNT palette entries starting from INDEX in the
Falcons 256 colour palette.

All of the palette handling routines also apply to the NON-ST COMPATABILITY
bit-plane based modes (ie. not true colour, or ST comp.)

df videl n,h,s,o,p,v,8,c

This instruction defines a video mode N, which can range from 1-9. This mode is
defined by the remaining flags. The value of these flags does not matter (with
the exception of c) To set a flag, give a non-zero value. The meanings of thes
flags are :-

h - vertical height (double line / interlace)
s - ST compatibility mode
o - overscan (enabled)
p - PAL / NTSC (ie set = 50Hz, clear = 60 Hz)
v - VGA mode
8 - set 80 column mode
c - Number of colours. Valid values=2,4,16,256,65536. Other values give 2.

eg.
df video 1,1,0,0,0,1,0,65536 would set 320x240x65536 on a VGA monitor

Please make ALL programs both VGA and RGB compatible. There is a small enough
user base, even without dividing it!!!

NOTE: 640x?x65536 is not a valid mode for a VGA monitor....

falc bar col,x1,y1,x2,y1,scr

This instruction draws a filled bar on the screen at address SCR. This screen
is assumed to be of the resolution / colour depth as the current one. The
co-ordinates of the bar are given by x1,y1,x2,y2 assuming the first pair to be
the top left corner, and the second the bottom right.

It is drawn in the current colour.

falc box x1,y1,x2,y2,scrn

This instruction draws a hollow box on the screen at address SCR. The screen is
assumed to be of the same dimensions/colour depth as the current screen. The
top left corner is drawn at the point (x1,y1), and the bottom left corner at
the co-ordinates (x2,y2).

It is coloured with the current colour.

falc cls scr_address

This instruction clears the screen at the given address. It uses the blitter in
HOG mode, so do not use if another extension is utilising the BLiTTER in
interleave mode. The entire screen (even with a virtual screen) is filled with
colour 0.

There have been a couple of errors caused by this command... untraced...

falc colour index,red,green,blue

This instruction sets colour number INDEX in the palette to the colour made up
of the components RED,GREEN and BLUE. Each of these can range from 0-63. So,
white is defined as 63,63,63.

falc draw screen,x1,y1,x2,y2

This instruction will draw a line in the currently selected colour on the
screen at address SCREEN from coordinates X1,Y1 to X2,Y2. At the moment, only
horizontal and vertical lines will be drawn, and only in true-colour modes.
This will change soon...

falc ink index

falc ink red,green,blue

This instruction sets the current colour for all (my) graphics routines. The
value index is the 16-bit colour value when in true-colour mode, otherwise it
is the index of the colour in the palette (0-255).

If the three value version is used in true colour mode, then the three values
will be combined to make the 16-bit colour from the red,green and blue
components. It should be noted that to ensure that the collision bit is not
set, an even value should be passed for green.

n=falc mkey

This funtion returns the state of the mouse buttons when using the mouse
routine from this extension. The value return is encoded in the same way as the
equivelent STOS routine - ie : 0=none, 1=left, 2=right, 3=both.

falc mouse off

This instruction switches off the Falcon extension mouse command, and restores
the STOS mouse routine.

falc mouse on

This instruction enables a mouse routine which is able to go beyond the screen
size of ST-high. It takes the maximum dimension of the screen from the current
dimensions. Thus, if using a 800x600 virtual screen, this is the range of the
mouse co-ordinates.

It should be noted, that unlike the STOS mouse routines, a pointer is NOT
displayed at the current postition of the screen. If this is desired, tc
sprite/tc copy can be used in true-colour mode.

falc plot screen,x,y

This instruction plots point (x,y) on screen with the current colour. The
routine is faster than the STOS 'PLOT' command, even though it supports
4/16/256 and true-colour modes!!

falc set mouse x,y

This instruction sets the current position of the mouse cursor to the
coordinates (X,Y) as given.

falc set zone n,x1,y1,x2,y2

This instruction defines a zone which can be tested for the presence of the
mouse. X1,Y1 is the co-ordinate pair of the top-left corner of the box to be
defined. X2,Y2 is the co-ordinates of the bottom right hand corner. N is the
number of the zone to be defined, and may range from 0 to 63



n=falc x mouse

This function returns the x co-ordinate of the mouse pointer when using the
mouse routine in this extension.

n=falc y mouse

This function returns the y co-ordinate of the mouse pointer when using the
mouse routine in this extension.

n=falc zone(m)

This function returns whether or not zone number M contains the mouse-pointer
or not. The value returned is either TRUE (-1) or FALSE (0)

fpal adr,index,count

This instruction copies the palette to the memory starting at ADR. INDEX is the
number of the first palette to store, and COUNT is the number to store. The
data is stored in the same format as SET FPAL.

gdos font n,addr

This instruction sets which font will be used by tc text. ADDR holds the
address of the font, and N is the number of the font in the data to use (More
than once size may be held in one data-block).

Although the routine uses GDOS fonts, currently only the system font is
supported. This will change very soon. This routine has been included at this
stage as not all OS versions have the font at the same address.

To find the system font in memory, use a memory searcher program (such as MON
from devpac) to search for the string "system", as this is in the font name.
The data should say "8x8 system font" (or 6x6 or 8x16). This address-4 should
be passed to this instruction. On my TOS 4.04 Falcon the following addresses
were found: (addresses as passed to instruction)

   * 6x6 - $e4afec
   * 8x8 - $e4b6c8 (This address is used by default)
   * 8x16- $e4d124

If a value of 0 is passed in ADDR, then the last address used will be retained.
In my Falcon, if N is 1, and ADDR=8x8 font then the 8x16 is used.)

goraud scr,col,x1,y1,i1,x2,y2,i2,x3,y3,i3

This instruction draws a goraud shaded triangle on a true colour screen at
address SCR. x1-x3 and y1-y3 are the co-ordinates of each of the three corners.
i1-i3 are the relative inensities of the three points. This may range from 0 to
$7fff.

The corners should be specified in a clock-wise direction.

COL determines the colour. The valid values are :-
0 - Red
1 - Green
2 - White
3 - Brown/orange

If the colour is anything other than these, it will be assumed to be the
address of the colour table. The colour table consists of 32 words, each a true
colour value. word no. 0 is the darkest and word no. 31 the brightest. This
must be followed by 16 empty words.

NOTE: CANNOT BE COMPILED.

init goraud

This instruction sets up various parameters for the Goraud routine (see above).
This MUST be called before goraud.

NOTE: CANNOT BE COMPILED.

init virtual xres,yres

This command initialises a virtual screen of dimensions XRES by YRES. The
actual resolution of the screen / number of colours is determined by the
current screenmode. Calling setvideo 0 will restore the screen.

x=planes

This function returns the number of bit-planes in the current screenmode. The
values returned are 1,2,4,8 and 16.

x=quick fade(colour)

This function fades a 256 colour palette to the given colour. The colour is
stored as a 18-bit number, where the top 6 bits represent the Red component,
the next 6 are the Green component, and the bottom 6 bits are the Blue
component.

The returned value, x is the number of palette entries changed.

NOTE: There seems to be some inteference at the top of the screen ?!?

x=scrsze(videomode)

This function returns the amount of memory taken for a given screenmode. The
value VIDEOMODE is the number (0-9) of the defined video mode.

This function does not take account of any virtual screen, or expanded screen
(using set fv)

set fpal addr,index,count

This instruction sets the Falcons 256 colour palette. ADDR stores the address
at which the first palette entry is held. INDEX stores the first register to
change, and count is the number of colour registers to change.

The data is stored longwords in the XRGB format of the XBIOS. An array can be
used to hold the palette data, with the address passed using varptr.

eg.
set fpal VARPTR(MYPAL(0)),0,256

set fv addr

This command allows the use of non-standard screen resolutions by setting the
video registers to those specified in a FV (version 2) file. The address of the
start of this file is passed in the parameter ADDR.

Note that FV files are, by their very nature, dangerous, as setting the
registers to incorrect values could be harmful to your monitor. I take no
responsibility for any problems caused by using this command. Having said this
I have synced my SVGA up to 100Hz, and have had no adverse effects...

set video n

This instruction sets the video mode to a previously defined mode. N may range
from 0-9. Video mode 0 is set to the video mode which is chosen at boot-up of
STOS (ie ST Medium / ST High) - and is changed by the ST COMPAT command to the
new default resolution.

On TOS < 4.04, when changing from an ST mode, a bus error / illegal
instructions are caused by the operating system. Unfortunately, as STOS forces
the Falcon into an ST mode, every time this instruction is executed on < TOS
4.04 it will crash your machine. If compatibility is essential, then use set fv
to change the video mode.

st compat n

This command switches the video mode from one ST screen mode to another. It
initialises both this extensions graphics commands, and the STOS routines for
the new mode. N may range from 0 to 2, where 0 is ST Low and 2 is ST High.

The command should work on an ST (although cannot switch to ST High).

At this time, it is neccesary to use the DEFAULT command after this instruction
as It does not completely re-initalise STOS. I hope to remove this problem.

x=tc collide

This command returns a value to indicate whether or not a collision occured
during the previous sprite plot. A value of 0 is returned if no collision
occured, or 1 if a collision was detected.

Unlike the STOS collide routine, this is pixel perfect - ie the object may be
any shape, with only one pixel overlapping, and a collision will be detected.
However, for this to work, somewhere the sensative parts of the screen (for
backgrounds may also be sensative) must be stored. I have chosen to store this
information in bit 5 (The LSB of the green part of the colour). This is because
this bit does not make a noticable difference in colour, and it is used for
other things (such as the genlock alpha channel).

The test is performed on any part of the sprite being ploted (non see-though)
to test whether bit 5 is set in the background.

If using this command in conjunction with tc alpha, then ensure that bit 5 is
not masked out by the alpha command.

tc copy scr1,x,y,w,h,scr2,x2,y2

This instruction copys a block of width W and Height H from the point (X,Y) on
the screen at address SCR1 to the screen at address SCR2, with the top left
corner at the point (X2,Y2). This instruction uses the BLiTTER chip in HOG mode
to perform the operation, so do not use the blitter extension to start a copy
in shared mode and then call this instruction.

NOTE: Dont pass -ive width and height parameters! I tried this, and it caused
my machine to reboot, and trashed the NVRAM !!!!!

x = tc fade(length,address)

This function fades a True Colour screen towards the currently selected colour.
The ADDRESS is the start of the screen to fade. LENGTH is the length of the
part to fade. (ie the length of 1 screen if the whole screen is to be faded.)

The returned value is the number of pixels that were faded. When this value is
zero, the whole screen has be faded to the given colour.

z=tc point screen,x,y

This returns the RGB value z, of the pixel on screen at coordinate (x,y) in
True Colour mode. This command has the same purpose as the STOS command point.

tc scrn fade screen1,screen2,length

This instruction fades one True Colour screen into another. Simply pass the
addresses of the screens as parameters, and the length.Both screens must be of
the same size.

tc sprite x,y,n,scr,spr

This instruction draws a sprite created with Spooky Sprites (by Johan Karlsson
- [e-mail] ) in true colour mode. X and Y are the co-ordinates at which
to plot the sprite. N is the number of the sprite to draw. SCR is the address
of the screen, and SPR is the address of the sprite bank.

Currently, clipping is only supported vertically on UNPACKED sprites. However,
further support is on the way...

tc text screen,x,y,string$

This instruction will print the string stored in STRING$ on the screen at
address SCREEN at coordinates X,Y. It will be printed in the current font (not
the STOS one) The text is plotted in the currently set colour, using FALC
COLOUR.

Future versions (very soon) will support GDOS fonts, stored at the given
address. However, only fonts with the data in motorola format will be supported
as I dont want to slow the printing down by supporting both Intel and Motorola
formats.

INFO: Motorola / Intel format:
Motorola format is where 2 byte values are stored HIGH BYTE | LOW BYTE. (ie
with the bits from left to right decreasing in significance.)

Intel format is where 2 byte values are stored LOW BYTE | HIGH BYTE. Thus, to
convert from one format to the other requires that the two bytes are switch
order. I will supply a STOS program which will detect whether it is a motorola
or intel font, and to convert an intel format one into a motorola. You are free
to use it in any program you like to allow all GDOS (not Speedo) fonts to be
used by you programs.

tga decode tga_addr,dest_addr

This instruction will decode a type 2 targa (.TGA) picture. The targa should be
at the address TGA_ADDR, and the destination screen should be at DEST_ADDR. The
screen is assumed to be of the correct size for the targa, and is assumed to be
a true-colour screen.

To ensure that you reserve enough memory for the decoded picture, the size can
be calculated by:

width * height * 2

The source and destination addresses should be different, as corruption will
occur in most pictures - only those stored left-to-right and top-to-bottom will
not be corrupted by decompressing over the original file.

The decode routine only supports type 2 targas. These are by far the most
common type, and are uncompressed true colour images. (15/16/24/32 bit). The
routine does however support any of the four orientations in which the picture
may be stored.

x=tga height(addr)

This function returns the height in pixels of the targa at ADDR. This is useful
for calculating the amount of space required for the picture.

x=tga width(addr)

This function returns the width in pixels of the targa at ADDR. This is useful
for calculating the amount of space required for the picture.

virtual x,y,screen

This command positions the view-port in a virtual screen. The virtual screen
should start at SCREEN, and X,Y should be the co-ordinates of the top-left
pixel to be displayed on screen.

Currently in bit-plane modes, only screens with X a multiple of 16 will be
displayed correctly. In true-colour mode, X must be a multiple of 2.

The virtual screen is achieved through the 'Hardware Scrolling' hardware, and
so can be used to implement infinite scrollers...

X=xres

This function returns the horizontal resolution in pixels. This includes any
virtual screen that is in use, and will take account of unusual modes defined
with a .FV file.

Y=yres

This function returns the vertical resolution in pixels. This includes any
virtual screen that is in use, and will take account of unusual modes defined
with a .FV file.

Sound

dsp clear

This command can be used to reset the entire sound sub-system. It does this
using the XBIOS call Sndstatus, however, it does not perform exactly as the
system call.

The command flushes the DSP of all subroutines, and then tri-states it
(disconnecting it from the sound-system). All DSP interupts are disabled, and
all conections (not just the DSP) in the sound system are disconected. The
sample playback resolution is set to 8-bit stereo, and all DMA transfers are
halted.

However, unlike the XBIOS, the gain and attenuation (volume) settings are not
cleared, and the PSG and the Matrix are both connected to the audio output.

This command should be used to clear the sound-system if an error occurs, or to
remove a DSP routine which has been loaded in (either with TRAP or with the DSP
PROCESS command).

All internal flags are cleared, and so, any play routines will not need the
corresponding stop. (eg DTM PLAY start(14),155555 : DSP CLEAR would not need a
DTM STOP command, as DSP CLEAR would do this.)

dsp play modaddress

This instruction plays a 4-track mod file on the DMA sound system using the
DSP. This causes little slowdown, unlike other replay routines.

Due to a bug in part of the code (not by me), the file "dspmod.bsw" must be
loaded each time a module is played. This file is read by the extension from
the current directory. If the file could not be found, the "Not done" error
will be returned.

(for those who wish to know why, the code cannot be run twice, as it seems to
modify itself {or a variable} causing an illegal instruction.)

modaddress is the address at which the module can be found. If this is a memory
bank, it must be specified as start(10), not as 10.

eg.
10 reserve as work 15,195636 : load "bubleman.mod",15 : dsp play

dsp process file$,buffer,mode

This instruction allows you to process audio data with the DSP. The DSP load
file (.LOD) FILE$ is loaded into the dsp with the DSP_LoadProg call. BUFFER
should point to an area of space which can be used to process the .LOD file.
The size of this area is "3 * (length of program / data words + (3 * no of
blocks in program))".

MODE is a value which indicates what you wish to be processed. There are
currently 3 modes. These are:

   *  0 : Process audio through. Data is passed from the ADC -> DSP -> DAC, and
     so provides real-time processing.
   *  1 : Process audio record. Whenever FALC SAMPLE is called, the data is
     passed via the DSP, enabling filtering etc. to be performed at record
     time.
   *  2 : Process audio playback, Whenever FALC SAM PLAY is called, the sample
     is passed through the DSP, enabling effects to be performed on previously
     recorded data.

A forth mode may be added, which takes a sample in memory, processes it, and
places it back in memory. This would allow perminant processing.

For further details, see the example .LOD files, and related documentation.

dsp stop

This instruction stops the dsp module that currently is playing. If the mod is
left playing, and the memory is re-allocated (eg exiting STOS), the code will
cause a bus error (probably...)

X$=dtm inst (number,addr)

This function returns the name of instrument no. NUMBER in the DTM module at
address ADDR. The name is returned in the form of a string. The instrument name
is often used to store information about the module, writen by the composer.

eg.

10 reserve as work 10,355000 : bload "test.dtm",10
20 i$=dtm inst(1,start(10)) : print i$

will print the name of the first instrument in the DTM module TEST.DTM.

x$=dtm name(addr)

This function returns a string containing the name of a DTM module at address
ADDR.

eg.

10 reserve as work 10,355000 : bload"test.dtm",10

20 i$=dtm name(start(10)) : ? i$

will print the name of the module TEST.DTM

dtm play dtmaddr,length

This instruction plays a Digital Tracker Module using the DSP and the Audio
sub-system. The address of this module should be passed in the dtmaddr
parameter, and also the LENGTH of the file.

When reserveing the space for the module, you must reserve an extra 200000
bytes, as this is used as temporary storage by the player routine.

The current version of the player only supports 8-bit mono samples, and only
modules with an even number of voices (up to 32 tracks!!!)

NOTE: CANNOT BE COMPILED

dtm stop

This instruction stops a piece of DTM tracker music.

NOTE: CANNOT BE COMPILED

X=dtm voices addr

This function returns an the number of voices (or tracks) that the DTM module
at address ADDR uses. This command can be used to test that the module uses an
even number of tracks, as the current replay routine does not support modules
with an odd number of tracks.

falc freq value

This instruction selects what frequency should be used for DMA sound (ie for
DSP PROCESS, and FALC SAMPLE / SAMPLAY. The change will only take effect when
the next command using the DMA is called.

There are 8 different frequencies available. These are coded in the following
way:

  1 = 49170 Hz          5 = 16390 Hz
  2 = 32780 Hz          7 = 12292 Hz
  3 = 24585 Hz          9 =  9834 Hz
  4 = 19668 Hz         11 =  8195 Hz

All other values will give a MUTE condition (ie it wont play....).

NOTE: The frequency encoding is likely to change, to allow for 50, 25.5 and
12.5 Khz freqencies also supported by the DMA.

Falc mic thru

This instruction toggles the microphone through, and the PSG output. Both are
mixed with the output of the matrix (ie DMA/DSP). This can be used to allow the
output of an external device such as a walkman through you Falcons speakers.

Falc sammde x

This instruction sets the resolution of sample playback. The value X gives the
mode. Valid modes are :-

0 - 8 bit stereo
1 - 16 bit stereo
2 - 8 bit mono
This call does not effect recording mode - all recording is done at 16 bit
stereo.

Falc samplay start,end,loop

Using this command a sample starting at address START and ending at END can be
played on the Falcons DMA sound-system. The sample is played at the currently
selected frequency.

The value LOOP indicates whether or not the sample should be looped. If the
value is zero, the sample will not be looped, otherwise, it will be.

There are 8 different frequencies available. These are coded in the following
way:

  1 = 49170 Hz          5 = 16390 Hz
  2 = 32780 Hz          7 = 12292 Hz
  3 = 24585 Hz          9 =  9834 Hz
  4 = 19668 Hz         11 =  8195 Hz

All other values will give a MUTE condition (ie it wont play....).

NOTE: The frequency encoding is likely to change, to allow for 50, 25.5 and
12.5 Khz freqencies also supported by the DMA.

Falc sample start,end

This command uses the Falcons 16-bit sampling hardware to record a sample into
memory starting at START. END is the end of the record buffer, and the sample
will not exceed this buffer. Although it doesn't pass the end, sound can still
be heard even when the buffer is full. Stop this with FALC MIC THRU.

The sample is recorded at the current frequency. Remember that all recording is
done in 16-bit stereo, whatever mode has been set.

X=Falc sampos(mode)

This function returns the address of the current sample being played or
recorded. Which is returned is determined by the value MODE. If mode=0, then
the record pointer will be returned, otherwise, the playback pointer is
returned.

There are two uses for this instruction. One to find the end of a sample.

Eg.
10 falc samplay strt,end,freq
20 repeat
30 until (falc sampos(0)>end)
40 falc samstop

This program would stop the sample when it reaches the end.

Or, alternatively, it can be used to find the current samples value.
Eg.
10 falc sammde 0
20 falc samplay strt,end,freq
30 repeat
40 plot x,100 : x=peek(falc sampos(0)) : plot x,100
50 until (falc sampos(0)>end)
60 falc samstop

This program would play an 8-bit mono sample, and plot a single point on its
waveform. This could be used to constuct an osciliscope display. If the sample
is stereo, the right sample comes imedately after the left.

Falc samstop

This instruction halts all DMA sound interupts (both record and playback). Note
that this does not disconnect the microphone throughput, or stop any PSG based
sound.

set gain l,r / x=lgain / x=rgain

LGAIN and RGAIN return the left and right input gains. Set gain, sets the left
and right gains to L and R. All values range from 0 to 15. Each step is a gain
of 1.5 dB.

This is done with the XBIOS command (not using the memory location.)

set volume l,r / x=lvolume / x=rvolume

LVOLUME and RVOLUME return the left and right output volumes. Set volume sets
the left and right volumes to L and R. All values range from 0 to 15. Each step
is a decrease of 1.5 dB.

speaker on / speaker off

These two instructions switch on/off the internal speaker.

programs should give the user the choice of having it on/off, since not all
users have external speakers, and VGA monitors do not include speakers.

X$=tracker inst (number,addr)

Like the command DTM INST, this function returns the name of instrument No.
NUMBER in the .MOD module at the address ADDR.

tracker name (addr)

This command is similar to DTM NAME, and performs the same task - returning the
name of a module at address ADDR, but for a .MOD module. The name is returned
in the form of a string, which is never over 20 characters in length.

Instructions in progress

In the current version of this extension, incomplete instructions are included.
These will, in general, cause some kind of error (eg bus / syntax) if called
(plus I dont tell you the necessary parameters ;-)

I hope to replace all of the TC commands with a FALC version. This will detect
the current screenmode, and draw etc. in the correct way. TC GORAUD may be an
exception to this....

comming soon....

   * tc alpha - make TC sprites translucent.
   * .AVR file support.
   * optimised bitplane graphics.
   * bitplane mode sprites.
   * falc draw.
   * Extension for registered users only. (watch out for more details...)

Version history :-

Work for this extension began on 10 December 94 (I think).

V0.1
     First interpreter extension code (ever!!!)
     With instructions - set fv, get fv, cookie and speaker on / off, goraud
     (not working).
V0.2
     Added gain, attenuation, jagpad (not working), dsp play, dsp stop.
     Installed start-up code.
V0.3
     Removed set fv, get fv.
     Added set videl, videl, monitor, os version.
     Fixed DSP play.
V0.4
     Added tc fde, tc scrn fde, my fde, tc plt, tc pnt, scrsze.
     Fixed start-up for RGB (I think - not tested)
     Changed gain etc. to use XBIOS calls, rather than memory location.
V0.4a
     Fixed scrsze (typo), and added checking to DSP play/stop to prevent errors
     due to the other not being called ( ie DSP stop with no play) Finally
     coded jagpad (why did Atari make it so complex?!?)
     Completed quick fade,tc point and tc plot.
V0.5a
     Started cycle, and started falc play.
     Fixed gain/attenuation to accept variables.
     Started DTM play / stop.
     Replaced set l/r atten with set volume.
     Replaced video mode routines
V0.5b
     Complete re-write from v0.3 ish due to source code being wiped.
     Added TC sprite and falc sammde.
     TC FADE/TC SCRN FADE/TC PLOT/TC POINT no longer work....
V0.5c
     Fixed the above (TC) routines.
     Fixed sprite/graphics routines to work with all resolutions.
V0.6
     Fixed start-up for RGB. Fixed DSP play bug.
     Completed goraud / init goraud / dtm play / dtm stop.
     Added TC bar / TC box.
     Started virtual/init virtual.
V0.7
     Added TC copy / set fpal / fpal.
     Completed cycle.
     Changed quick fade to 18-bit parameter, from palette form. Compiler now
     coming on-line.....
     - TC BOX/TC BAR/TC PLOT/TC POINT/DF VIDEO/SET VIDEO/ OS
     VERSION/COOKIE/LVOLUME/RVOLUME/SET VOLUME/LGAIN/ RGAIN/SET GAIN/TC FADE/TC
     SCRN FADE/QUICK FADE/ TC SPRITE/SPEAKER ON/SPEAKER OFF/MONITOR/SAM MODE
     and SCR SZE all now work compiled.....
V0.8
     Added falc mic thru / falc samplay / falc samstop / falc sampos.
     Added falc sample / set fv
     Added above commands to compiler.
     Added FPAL/SET FPAL/CYCLE to compiler.
     Fixed set video for TOS 4.02 (I HOPE!!!!! - NO. Try again....)
V0.9
     Split extension into 2 parts - due to limit of size.
     Added dtm name, tracker name, dtm voices, dtm inst, tracker inst to both
     Compiler and Interpreter extensions.
     Fixed goraud for any polygon (not just trianges).
     Added dsp process and dsp clear, falc freq, falc ink
     Fixed dtm play/dsp play clash.
V0.9a
     Fixed a few Compiler bugs.
     Completed falc cls. Finished init virtual/virtual
     Fixed tc box bug.
     Started bitplane mode graphics routines...
V0.9b
     Completed bitplane graphics for 4/16/256 colours.
     Fixed compiler DSP play.
     Added set cache,cache.
     Added st compat
V1.0
     Goraud polygon back to only triangles (so that it actually works!!)
     Added falc colour
     Various bug-fixes
     Example code for registered version available.
     Un-registered compiler extension now has start up message.
     Added falc help and lfalc help.
     Added xres,yres and planes.

V1.0a
     Added tga width, tga height and tga decode.
     Fixed yres
     Fixed falc mouse clipping.
     Falc mouse now compiles.
     Finally fixed setvideo for TOS 4.02 (OS bug...)
     Fixed TC sprite for compiler

V1.1
     Added tc text and tc collide
     Fixed a couple of minor bugs.
     Started tc alpha.
     Started .AVR reading code.
     Started falc draw

V1.1a
     Added gdos font
     Fixed bugs in tc text
     Added collide to compiler
     Falc draw partially implemented
     Made mouse routine more stable in editor

Future versions may include other commands, as I think of how to do them....
(such as more graphics functions; FLI player; d2d play and more...)

Credits :-

   * True colour sprite routine : Johan Karlsson
   * True colour fade : Genie! of Network Trash
   * Goraud polygon : Griff
   * DTM replay code : Jaccard Emmanuel
   * DSP tracker code : bITmASTER of BSW
   * FV file format : Johan Karlsson

All the rest is by me (Anthony Jacques)

Cheers to RiCH Davey for testing/suggesting commands, and Les Greenhalgh for
the tips on extension writing...



Anthony Jacques

WWW:   http://www.cs.mna.ac.uk/~jacquesa/
email: [e-mail]